package com.wg.game.app;

import com.wg.net.DisconnectReason;
import com.wg.net.session.ISession;

/**
 * 应用层核心接口（定义网络事件与应用逻辑的交互契约）
 * <p>
 * 职责：
 * - 管理连接生命周期事件（初始化、接收消息、断开连接）
 * - 处理出站连接状态（建立成功/失败）
 * - 提供与应用层业务逻辑的交互入口
 *
 * @author 少爷123
 */
public interface IApplication {

    /**
     * 连接初始化回调（当客户端/服务端完成握手后触发）
     *
     * @param session 会话对象（封装底层连接信息）
     * @param data    初始化请求的原始字节数据（可选，根据协议决定）
     */
    void onInit(ISession session, byte[] data);

    /**
     * 接收消息回调（当网络层收到对端数据时触发）
     *
     * @param session  会话对象
     * @param userData 应用层关联的自定义数据（由业务层设置）
     * @param data     接收到的原始字节数据（已通过编解码）
     */
    void onReceive(ISession session, Object userData, byte[] data);

    /**
     * 断开连接回调（当连接主动/被动断开时触发）
     *
     * @param session      会话对象
     * @param userData     应用层关联的自定义数据
     * @param reasonCode   断开原因代码（如超时、客户端主动关闭）
     * @param reasonDetail 断开详细说明（补充信息）
     */
    void onDisconnect(ISession session, Object userData, DisconnectReason reasonCode, String reasonDetail);

    /**
     * 出站连接建立成功回调（当本地主动发起的连接成功时触发）
     *
     * @param session  会话对象（对端连接信息）
     * @param userData 应用层关联的自定义数据（由业务层设置）
     */
    void onOutboundConnectionEstablished(ISession session, Object userData);

    /**
     * 出站连接失败回调（当本地主动发起的连接失败时触发）
     *
     * @param userData     应用层关联的自定义数据
     * @param errorCode    错误编号（协议定义的错误码）
     * @param errorMessage 错误描述（具体失败原因）
     */
    void onOutboundConnectionFailed(Object userData, int errorCode, String errorMessage);
}